@terrafirmagreg-team/kit 0.0.0-stage → 0.1.0

package/package.json

@@ -1,6 +1,71 @@
 {
   "name": "@terrafirmagreg-team/kit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "type": "module",
+  "exports": {
+    "./lib/*": [
+      "./src/lib/*.ts",
+      "./src/lib/*.tsx",
+      "./src/lib/*/index.ts",
+      "./src/lib/*/index.tsx"
+    ],
+    "./types/*": "./src/types/*.ts",
+    "./hooks/*": [
+      "./src/hooks/*.ts",
+      "./src/hooks/*.tsx",
+      "./src/hooks/*/index.ts",
+      "./src/hooks/*/index.tsx"
+    ],
+    "./types": "./src/types/index.ts",
+    "./components/*": [
+      "./src/components/*.ts",
+      "./src/components/*.tsx",
+      "./src/components/*/index.ts",
+      "./src/components/*/index.tsx"
+    ],
+    "./locales": "./src/locales.ts"
+  },
+  "dependencies": {
+    "@base-ui/react": "^1.9.0",
+    "@icons-pack/react-simple-icons": "13.15.1",
+    "@terrafirmagreg-team/translate": "0.1.0",
+    "@terrafirmagreg-team/ui": "0.1.0",
+    "fumadocs-core": "16.17.8",
+    "fumadocs-mdx": "15.4.10",
+    "fumadocs-twoslash": "^4.0.4",
+    "lucide-react": "^1.63.0",
+    "remark-directive": "^4.0.0",
+    "remark-gfm": "^4.0.1",
+    "remark-math": "^6.0.0",
+    "remark-parse": "^11.0.0",
+    "server-only": "^0.0.1",
+    "turndown": "^7.2.4",
+    "turndown-plugin-gfm": "^1.0.2",
+    "unified": "^11.0.5",
+    "zod": "4.6.7"
+  },
+  "peerDependencies": {
+    "next": ">=15",
+    "react": ">=19"
+  },
+  "devDependencies": {
+    "@types/mdx": "^2.0.14",
+    "@types/node": "^26.6.5",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "@types/turndown": "^5.0.6"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/TerraFirmaGreg-Team/Web-Foundation.git",
+    "directory": "packages/kit"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "styles",
+    "styles.css"
+  ]
 }

package/src/components/blocks/nav-title.tsx

@@ -0,0 +1,65 @@
+'use client';
+
+import { usePathname } from 'next/navigation';
+import type { ComponentProps } from 'react';
+
+import { uiConfig } from '@terrafirmagreg-team/ui/lib/config';
+import { SiteTitle } from '@terrafirmagreg-team/ui/components/blocks/nav/site-title';
+import { useAsyncValue } from '@terrafirmagreg-team/ui/hooks/use-async-value';
+import { clientDumpLoader } from '@terrafirmagreg-team/kit/lib/config';
+import {
+  datasetRef,
+  isDumpSection,
+  parseDatasetRef,
+  parseSectionLocation,
+} from '@terrafirmagreg-team/kit/lib/location';
+import {
+  setVersionPreference,
+  useVersionPreference,
+} from '@terrafirmagreg-team/kit/hooks/use-version-pref';
+import { VersionMenu } from '@terrafirmagreg-team/kit/components/version-menu';
+
+export function NavTitle({ className, ...props }: ComponentProps<'a'>) {
+  const { section, dataset } = parseSectionLocation(usePathname());
+  const datasetId = dataset ? parseDatasetRef(dataset).id : undefined;
+  const gameData = isDumpSection(section);
+  const pref = useVersionPreference(datasetId);
+  const version = useAsyncValue(
+    dataset
+      ? () =>
+          clientDumpLoader()
+            .loadDump(dataset)
+            .then((dump) => dump?.manifest.pack?.version ?? undefined)
+      : false,
+    [dataset],
+  );
+  const versions = useAsyncValue(
+    datasetId ? () => clientDumpLoader().loadVersions(datasetId) : false,
+    [datasetId],
+  );
+  return (
+    <SiteTitle
+      href="/"
+      icon={uiConfig().brand?.icon ?? ''}
+      name={uiConfig().brand?.name ?? ''}
+      subtitle={
+        dataset && datasetId ? (
+          <VersionMenu
+            section={section}
+            datasetId={datasetId}
+            currentRef={gameData ? dataset : datasetRef(datasetId, pref)}
+            label={gameData ? version : (pref ?? version)}
+            versions={versions}
+            onSelect={
+              gameData || !datasetId
+                ? undefined
+                : (next) => setVersionPreference(datasetId, next)
+            }
+          />
+        ) : undefined
+      }
+      className={className}
+      {...props}
+    />
+  );
+}

package/src/components/docs-image.tsx

@@ -0,0 +1,49 @@
+import { ImageZoom } from '@terrafirmagreg-team/ui/components/mdx/image-zoom';
+import { resolveSrc } from '@terrafirmagreg-team/kit/lib/pack-assets';
+import type { DocsImageProps } from '@terrafirmagreg-team/kit/types/mdx';
+
+export function DocsImage({
+  src,
+  pack,
+  mod,
+  path,
+  alt = '',
+  width,
+  height,
+  className,
+  caption,
+  defaultPack: pagePack,
+  ...rest
+}: DocsImageProps) {
+  const packHint = pack ?? pagePack;
+  const resolved = resolveSrc({ src, pack, mod, path }, packHint);
+  if (!resolved) {
+    return (
+      <p className="not-prose text-sm text-muted-foreground">
+        Missing image source (set <code>src</code> or <code>mod</code>+
+        <code>path</code>; pack defaults from the docs slug).
+      </p>
+    );
+  }
+
+  const w = Number(width) || 960;
+  const h = Number(height) || 540;
+
+  return (
+    <figure className="not-prose my-4 space-y-2">
+      <ImageZoom
+        src={resolved}
+        alt={alt}
+        width={w}
+        height={h}
+        className={className}
+        {...rest}
+      />
+      {caption ? (
+        <figcaption className="text-center text-sm text-muted-foreground">
+          {caption}
+        </figcaption>
+      ) : null}
+    </figure>
+  );
+}

package/src/components/outline/dropdown.tsx

@@ -0,0 +1,67 @@
+'use client';
+import { Popover } from '@base-ui/react/popover';
+import { cn } from '@terrafirmagreg-team/ui/lib/utils/cn';
+import { useTranslations } from '@terrafirmagreg-team/translate/hooks/use-translations';
+import { ChevronDownIcon } from 'lucide-react';
+import { useState } from 'react';
+import { OutlineActiveHeading, OutlineList, OutlineProgress } from './list';
+import type { WorkspaceOutlineDropdownProps } from './types';
+
+export function WorkspaceOutlineDropdown({
+  trigger,
+  content,
+  header,
+  footer,
+  ...props
+}: WorkspaceOutlineDropdownProps) {
+  const t = useTranslations();
+  const [open, setOpen] = useState(false);
+
+  return (
+    <Popover.Root open={open} onOpenChange={setOpen}>
+      <Popover.Trigger
+        {...trigger}
+        className={cn(
+          'flex items-center gap-2 min-w-0 h-8 px-1.5 -mx-1.5 rounded-lg text-start text-sm transition-colors',
+          open
+            ? 'bg-accent text-accent-foreground'
+            : 'text-muted-foreground hover:bg-accent/60 hover:text-accent-foreground',
+          trigger?.className,
+        )}
+      >
+        <OutlineProgress className="shrink-0" />
+        <OutlineActiveHeading
+          fallback={t('ui.on_this_page')}
+          activeClassName="text-foreground"
+        />
+        <ChevronDownIcon
+          className={cn('size-3.5 shrink-0 transition-transform', open && 'rotate-180')}
+        />
+      </Popover.Trigger>
+      <Popover.Portal>
+        <Popover.Positioner
+          align="start"
+          sideOffset={8}
+          positionMethod="fixed"
+          className="z-50"
+        >
+          <Popover.Popup
+            {...content}
+            className={cn(
+              'flex flex-col w-88 max-w-(--available-width) max-h-[min(28rem,var(--available-height))] p-3 rounded-2xl border bg-popover text-popover-foreground shadow-xl outline-none origin-(--transform-origin) transition-[opacity,scale] duration-150 ease-[cubic-bezier(0.22,1,0.36,1)] data-starting-style:opacity-0 data-starting-style:scale-95 data-ending-style:opacity-0 data-ending-style:scale-95 motion-reduce:transition-none',
+              content?.className,
+            )}
+          >
+            {header}
+            <OutlineList
+              {...props}
+              className="py-1"
+              onSelect={() => setOpen(false)}
+            />
+            {footer}
+          </Popover.Popup>
+        </Popover.Positioner>
+      </Popover.Portal>
+    </Popover.Root>
+  );
+}

package/src/components/outline/index.ts

@@ -0,0 +1,10 @@
+export type {
+  OutlineStyle,
+  OutlineContent,
+  OutlineProps,
+  WorkspaceOutlineDropdownProps,
+  WorkspaceOutlinePopoverProps,
+} from './types';
+export { Outline, RightSidebarOutline } from './outline';
+export { WorkspaceOutlinePopover } from './popover';
+export { WorkspaceOutlineDropdown } from './dropdown';

package/src/components/outline/list.tsx

@@ -0,0 +1,120 @@
+'use client';
+import { type TOCItemInfo, useTOCSelector } from '@terrafirmagreg-team/kit/components/toc/base';
+import { useTOCItems } from '@terrafirmagreg-team/kit/hooks/toc';
+import * as Base from '@terrafirmagreg-team/kit/components/toc/base';
+import * as OutlineDefault from '@terrafirmagreg-team/kit/components/toc/default';
+import * as OutlineClerk from '@terrafirmagreg-team/kit/components/toc/clerk';
+import * as OutlineBlock from '@terrafirmagreg-team/kit/components/toc/block';
+import { cn } from '@terrafirmagreg-team/ui/lib/utils/cn';
+import {
+  type ComponentProps,
+  type CSSProperties,
+  type ReactNode,
+  useState,
+} from 'react';
+import type { OutlineStyle } from './types';
+
+const variants = {
+  normal: OutlineDefault,
+  clerk: OutlineClerk,
+  block: OutlineBlock,
+};
+
+const selectTopmost = (items: TOCItemInfo[]) =>
+  items.find((item) => item.active)?.original;
+const selectProgress = (items: TOCItemInfo[]) =>
+  (items.findLastIndex((item) => item.active) + 1) / Math.max(1, items.length);
+
+export function OutlineList({
+  style = 'block',
+  list,
+  className,
+  onSelect,
+}: OutlineStyle & { className?: string; onSelect?: () => void }) {
+  const items = useTOCItems();
+  const { TOCItems, TOCItem, TOCEmpty } = variants[style];
+
+  return (
+    <Base.TOCScrollArea className={className}>
+      <TOCItems {...list}>
+        {items.length === 0 && <TOCEmpty />}
+        {items.map((item) => (
+          <TOCItem key={item.url} item={item} onClick={onSelect} />
+        ))}
+      </TOCItems>
+    </Base.TOCScrollArea>
+  );
+}
+
+export function OutlineActiveHeading({
+  fallback,
+  className,
+  activeClassName,
+}: {
+  fallback: ReactNode;
+  className?: string;
+  activeClassName?: string;
+}) {
+  const items = useTOCItems();
+  const active = useTOCSelector(selectTopmost);
+  const [shown, setShown] = useState({ item: active, roll: 1 });
+  if (shown.item !== active) {
+    setShown({
+      item: active,
+      roll: items.indexOf(active!) >= items.indexOf(shown.item!) ? 1 : -1,
+    });
+  }
+
+  return (
+    <span
+      className={cn('flex min-w-0 overflow-hidden', active && activeClassName, className)}
+    >
+      <span
+        key={active?.url}
+        className="truncate motion-safe:animate-roll-in"
+        style={{ '--roll': shown.roll } as CSSProperties}
+      >
+        {active ? active.title : fallback}
+      </span>
+    </span>
+  );
+}
+
+export function OutlineProgress({
+  size = 16,
+  ...props
+}: ComponentProps<'svg'> & { size?: number }) {
+  const value = useTOCSelector(selectProgress);
+  const circle = {
+    cx: size / 2,
+    cy: size / 2,
+    r: size / 2 - 1.5,
+    fill: 'none',
+    strokeWidth: 1.5,
+  };
+  const circumference = 2 * Math.PI * circle.r;
+
+  return (
+    <svg
+      role="progressbar"
+      viewBox={`0 0 ${size} ${size}`}
+      width={size}
+      height={size}
+      aria-valuenow={value}
+      aria-valuemin={0}
+      aria-valuemax={1}
+      {...props}
+    >
+      <circle {...circle} className="stroke-current/25" />
+      <circle
+        {...circle}
+        stroke="currentColor"
+        strokeLinecap="round"
+        strokeDasharray={circumference}
+        strokeDashoffset={circumference * (1 - value)}
+        transform={`rotate(-90 ${circle.cx} ${circle.cy})`}
+        className="transition-[stroke-dashoffset] duration-300"
+      />
+    </svg>
+  );
+}

package/src/components/outline/outline.tsx

@@ -0,0 +1,49 @@
+'use client';
+import { useTOCItems } from '@terrafirmagreg-team/kit/hooks/toc';
+import { cn } from '@terrafirmagreg-team/ui/lib/utils/cn';
+import { useTranslations } from '@terrafirmagreg-team/translate/hooks/use-translations';
+import { TextIcon } from 'lucide-react';
+import {
+  RightSidebarPanel,
+  RightSidebarPortal,
+} from '@terrafirmagreg-team/ui/components/layouts/right-sidebar';
+import { OutlineList } from './list';
+import type { OutlineProps } from './types';
+
+export function Outline({ container, header, footer, ...props }: OutlineProps) {
+  const t = useTranslations();
+  const items = useTOCItems();
+  if (items.length === 0 && !header && !footer) return;
+
+  return (
+    <div
+      data-slot="outline"
+      {...container}
+      className={cn('flex min-h-0 flex-col overflow-clip', container?.className)}
+    >
+      {header}
+      <h3 className="inline-flex items-center gap-1.5 text-sm text-muted-foreground">
+        <TextIcon className="size-4" />
+        {t('ui.on_this_page')}
+      </h3>
+      <OutlineList {...props} />
+      {footer}
+    </div>
+  );
+}
+
+export function RightSidebarOutline({ container, ...props }: OutlineProps) {
+  return (
+    <RightSidebarPortal>
+      <RightSidebarPanel className="pt-8 pb-4">
+        <Outline
+          {...props}
+          container={{
+            ...container,
+            className: cn('flex-1', container?.className),
+          }}
+        />
+      </RightSidebarPanel>
+    </RightSidebarPortal>
+  );
+}

package/src/components/outline/popover.tsx

@@ -0,0 +1,76 @@
+'use client';
+import {
+  Collapsible,
+  CollapsibleContent,
+  CollapsibleTrigger,
+} from '@terrafirmagreg-team/ui/components/ui/collapsible';
+import { cn } from '@terrafirmagreg-team/ui/lib/utils/cn';
+import { useTranslations } from '@terrafirmagreg-team/translate/hooks/use-translations';
+import { ChevronDownIcon } from 'lucide-react';
+import { useEffect, useRef, useState } from 'react';
+import { useTreePath } from '@terrafirmagreg-team/ui/hooks/use-tree';
+import { OutlineActiveHeading, OutlineList, OutlineProgress } from './list';
+import type { WorkspaceOutlinePopoverProps } from './types';
+
+export function WorkspaceOutlinePopover({
+  container,
+  trigger,
+  content,
+  header,
+  footer,
+  ...props
+}: WorkspaceOutlinePopoverProps) {
+  const t = useTranslations();
+  const page = useTreePath().at(-1);
+  const ref = useRef<HTMLElement>(null);
+  const [open, setOpen] = useState(false);
+
+  useEffect(() => {
+    if (!open) return;
+    const onClick = (e: MouseEvent) => {
+      if (e.target instanceof Node && !ref.current?.contains(e.target))
+        setOpen(false);
+    };
+
+    window.addEventListener('click', onClick);
+    return () => window.removeEventListener('click', onClick);
+  }, [open]);
+
+  return (
+    <Collapsible
+      open={open}
+      onOpenChange={setOpen}
+      {...container}
+      className={cn('max-md:layout:[--toc-popover-height:--spacing(10)]', container?.className)}
+    >
+      <header ref={ref} className="bg-card">
+        <CollapsibleTrigger
+          {...trigger}
+          className={cn(
+            'flex w-full h-10 items-center gap-2.5 px-4 text-start text-sm text-muted-foreground focus-visible:outline-none',
+            trigger?.className,
+          )}
+        >
+          <OutlineProgress
+            size={18}
+            className={cn('shrink-0', open && 'text-primary')}
+          />
+          <OutlineActiveHeading
+            fallback={page?.name ?? t('ui.on_this_page')}
+            className={cn('flex-1 transition-colors', open && 'text-foreground')}
+          />
+          <ChevronDownIcon
+            className={cn('size-4 shrink-0 mx-0.5 transition-transform', open && 'rotate-180')}
+          />
+        </CollapsibleTrigger>
+        <CollapsibleContent {...content}>
+          <div className="flex flex-col px-4 max-h-[50vh]">
+            {header}
+            <OutlineList {...props} onSelect={() => setOpen(false)} />
+            {footer}
+          </div>
+        </CollapsibleContent>
+      </header>
+    </Collapsible>
+  );
+}

package/src/components/outline/types.ts

@@ -0,0 +1,29 @@
+import type { ComponentProps, ReactNode } from 'react';
+import type * as OutlineDefault from '@terrafirmagreg-team/kit/components/toc/default';
+import type * as OutlineClerk from '@terrafirmagreg-team/kit/components/toc/clerk';
+import type * as OutlineBlock from '@terrafirmagreg-team/kit/components/toc/block';
+
+export type OutlineStyle =
+  | { style?: 'block'; list?: OutlineBlock.TOCItemsProps }
+  | { style: 'normal'; list?: OutlineDefault.TOCItemsProps }
+  | { style: 'clerk'; list?: OutlineClerk.TOCItemsProps };
+
+export type OutlineContent = {
+
+  header?: ReactNode;
+
+  footer?: ReactNode;
+} & OutlineStyle;
+
+export type OutlineProps = OutlineContent & {
+  container?: ComponentProps<'div'>;
+};
+
+export type WorkspaceOutlineDropdownProps = OutlineContent & {
+  trigger?: ComponentProps<'button'>;
+  content?: ComponentProps<'div'>;
+};
+
+export type WorkspaceOutlinePopoverProps = WorkspaceOutlineDropdownProps & {
+  container?: ComponentProps<'div'>;
+};